---
title: Concepts
description: Learn about Terrateam concepts
tableOfContents:
  minHeadingLevel: 1
  maxHeadingLevel: 3
---

To effectively use Terrateam, it's important to understand its key concepts and terminology. In the following section, we'll explore the core components of Terrateam and how they work together to simplify your infrastructure management workflow.

:::note
The default settings work well for most teams. Customize only if you need things like automatic module handling, tailored workflows, or extra rules before applies run.
:::

## Dirspace

In Terrateam, a Dirspace is a fundamental concept that defines the scope of Terraform operations. It uniquely combines a `repository`, a `directory` within that repository, and a Terraform `workspace`, represented as a tuple `(repository, directory, workspace)`.

Dirspaces are discovered automatically by Terrateam whenever it detects Terraform configurations in your repository. Each directory containing Terraform files is associated with a Dirspace, using either the explicitly defined Terraform workspace or the default workspace (if no workspace is specified).

:::note
Terrateam executes operations like plan and apply within the context of a Dirspace which combines a directory and Terraform workspace.
:::

## Engine

Every Dirspace in Terrateam is executed using a specific engine, the tool responsible for running the `init`, `plan`, `apply`, and related steps. By default, this engine is the Terraform CLI, but Terrateam also supports OpenTofu, Terragrunt, Pulumi, CDKTF, and even fully custom engines.

The engine can be defined globally for the entire repository or overridden per workflow to suit different environments or teams.

For example, you might want to use OpenTofu in development and Terraform in production:

```yaml
workflows:
  - tag_query: "development"
    engine:
      name: tofu
  - tag_query: "production"
    engine:
      name: terraform
```

Terrateam uses this configuration to decide how to execute each Dirspace when a change is detected. If you define a custom engine, you can provide commands for each lifecycle step, giving you full control over the execution logic.

Learn more about configuring an [Engine here](/reference/configuration/engine).

## Changes and File Patterns

When a pull request is opened or updated, Terrateam detects changes based on patterns defined in your `.terrateam/config.yml` file under the [`when_modified`](/reference/configuration/when-modified) configuration. The default configuration looks like:

```yaml
when_modified:
  file_patterns:
    - '${DIR}/*.tf'
    - '${DIR}/*.tfvars'
```

This configuration instructs Terrateam to monitor changes to any files with `.tf` or `.tfvars` extensions. Adjust these patterns in your configuration file to align with your project's structure.

:::tip[Configuration Flexibility]
The `when_modified` configuration can be set at three levels:
- **Global** - Applied to all directories
- **Directory** - Under `dirs.<directory>.when_modified`
- **Workspace** - Under `dirs.<directory>.workspaces.<workspace>.when_modified`

All three levels use identical syntax. More specific configurations override broader ones.
:::

Terrateam maps detected changes to their appropriate [Dirspaces](/getting-started/concepts#dirspace). These mapped Dirspaces are referred to as Changes. When executing operations, Terrateam only considers Dirspaces with modified files in the pull request.

## Auto-Plan and Auto-Apply

Terrateam provides automated Terraform execution workflows to simplify infrastructure changes:

- **Auto-Plan**: Runs `terraform plan` automatically when a pull request is created or updated. Enable with:
  ```yaml
  when_modified:
    autoplan: true  # Set to false to disable
  ```
- **Auto-Apply**: Runs `terraform apply` post-merge. It is disabled by default. Enable with:
  ```yaml
  when_modified:
    autoapply: true
  ```

## Tags and Tag Sets

Terrateam uses [Tags](/advanced-workflows/tags) to organize Terraform resources through flexible labeling. Tags provide a powerful way to categorize, filter, and manage your infrastructure resources, making it easier to apply specific operations to targeted sets of resources.

Tags in Terrateam can be both user-defined and automatically assigned. They are optional but provide significant benefits for organizing and managing infrastructure resources.
:::note
Users can define custom tags in their Terrateam configuration file (`.terrateam/config.yml`).
:::

There are two types of Tags:

- **Tag Set**: An unordered and deduplicated list of labels assigned to Terraform resources.
- **Tag Query**: A Tag Set used for matching. Every Tag in a Tag Query must exist in a Tag Set for a match to occur. Check the [Tag Queries](/getting-started/tag-queries) page to lean more.

## Lock policy

Terrateam's locking system prevents concurrent modifications by ensuring only one change can be applied to a resource at a time. This prevents:

- State file conflicts.
- Resource modification races.
- Concurrent apply operations.

Key behaviors:
- Enabled by default (no config needed).
- Automatically released after apply + merge.
- Force unlock via comment: `terrateam unlock`.

Customizing lock policies:
```yaml
# .terrateam/config.yml (default shown)
workflows:
  lock_policy: strict  # strict|apply|merge|none
```

For advanced configurations see our [Locks & Concurrency guide](/advanced-workflows/locks-and-concurrency).
